plot3D (version 1.4)

images in 3D frame: Images in 3-D plots.

Description

image3D adds an image in a 3-D plot.

Usage

image3D (x = NULL, y = NULL, z = NULL, ..., colvar = NULL, 
      phi = 40, theta = 40, col = NULL,
      NAcol = "white", breaks = NULL, border = NA, facets = TRUE,
      colkey = NULL, resfac = 1, panel.first = NULL,
      clim = NULL, clab = NULL, bty = "b",
      inttype = 1, add = FALSE, plot = TRUE)

Value

Returns the viewing transformation matrix. See trans3D.

Arguments

x, y, z

Matrix (2-D), vector, or one value containing the values where the image is to be plotted. At least one of them should be one number, as this will determine where the image is plotted, parallel to the (y-z) plane (x one number), to the (x-z) plane (y one number) or to the (z-y) plane (z one number).

If two are vectors, the first vector should be of length equal to nrow(colvar) and the second should be of length equal to ncol(colvar).

colvar

The variable used for coloring.

col

Color palette to be used for the colvar variable.

NAcol

Color to be used for NA values of colvar; default is ``white''.

breaks

a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning.

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of side, plot, length, width, dist, shift, addlines, col.clab, cex.clab, side.clab, line.clab, adj.clab, font.clab and the axis parameters at, labels, tick, line, pos, outer, font, lty, lwd, lwd.ticks, col.box, col.axis, col.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las. The defaults for the parameters are side = 4, plot = TRUE, length = 1, width = 1, dist = 0, shift = 0, addlines = FALSE, col.clab = NULL, cex.clab = par("cex.lab"), side.clab = NULL, line.clab = NULL, adj.clab = NULL, font.clab = NULL) See colkey.

The default is to draw the color key on side = 4, i.e. in the right margin. If colkey = NULL then a color key will be added only if col is a vector. Setting colkey = list(plot = FALSE) will create room for the color key without drawing it. if colkey = FALSE, no color key legend will be added.

clab

Only if colkey = TRUE, the label to be written on top of the color key. The label will be written at the same level as the main title. to lower it, clab can be made a vector, with the first values empty strings.

clim

Only if colvar is specified, the range of the color variable, used for the color key. Values of colvar that extend the range will be put to NA.

resfac

Resolution factor, one value or a vector of two numbers, for the x and y- values respectively. A value > 1 will increase the resolution. For instance, if resfac equals 3 then for each adjacent pair of x- and y-values, z will be interpolated to two intermediary points. This uses simple linear interpolation. If resfac is one number then the resolution will be increased similarly in x and y-direction.

theta, phi

The angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. see persp.

border

The color of the lines drawn around the surface facets. The default, NA, will disable the drawing of borders.

facets

If TRUE, then col denotes the color of the surface facets. If FALSE, then the surface facets are colored ``white'' and the border (if NA) will be colored as specified by col. If NA then the facets will be transparent. It is usually faster to draw with facets = FALSE.

panel.first

A function to be evaluated after the plot axes are set up (and if applicable, images or contours drawn) but before any plotting takes place. This can be useful for drawing background grids or scatterplot smooths. The function should have as argument the transformation matrix, e.g. it should be defined as function(pmat). See example of persp3D and last example of voxel3D.

bty

The type of the box, the default only drawing background panels. Only effective if the persp argument (box) equals TRUE (this is the default). See perspbox.

inttype

The interpolation type to create the polygons, either taking the mean of the colvar variable (inttype = 1, 3 or extending the x, y, z values (inttype = 2). Values 1, 3 differ in how they treat NAs in the colvar variable. For inttype = 3, NAs are removed before taking averages; this will tend to make the NA region smaller. NAs are included when inttype = 1. This will tend to make the NA region larger. see details and an example in persp3D.

add

Logical. If TRUE, then the image will be added to the current plot. If FALSE a new plot is started.

plot

Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).

...

additional arguments passed to the plotting methods.

The following persp arguments can be specified: xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, scale, expand, box, axes, nticks, ticktype. The arguments xlim, ylim, zlim only affect the axes. All objects will be plotted, including those that fall out of these ranges. To select objects only within the axis limits, use plotdev.

In addition, the perspbox arguments col.axis, col.panel, lwd.panel, col.grid, lwd.grid can also be given a value.

shade and lighting arguments will have no effect.

alpha can be given a value inbetween 0 and 1 to make colors transparent.

Also the arguments lty, lwd can be specified (when border is not NA).

The arguments after ... must be matched exactly.

Author

Karline Soetaert <[e-mail]>

Details

image3D calls the surf3D function. The x, y, and z values are expanded as a matrix.

See Also

surf3D for the function on which image3D is based.

image2D for plot3Ds 2-D image function.

Examples

# save plotting parameters
 pm <- par("mfrow")

## =======================================================================
## images in x, y, z plane
## =======================================================================

 par(mfrow = c(2, 2))

# images in x, y, z plane
# We use colkey = list(plot = FALSE) to create room for a color key
 image3D(y = seq(0, 1, 0.1), z = seq(0, 1, 0.1), x = 0.5, 
   col = "blue", xlim = c(0,1), colkey = list(plot = FALSE))
 image3D(x = seq(0, 1, 0.1), z = seq(0, 1, 0.1), y = 0.5, 
   add = TRUE, col = "red", alpha = 0.2)   # alpha makes it transparent
 image3D(x = seq(0, 1, 0.1), y = seq(0, 1, 0.1), z = 0.5, 
   add = TRUE, col = "green")
 colkey(col = c("green", "red", "blue"), clim = c(0.5, 3.5), 
   at = 1:3, labels = c("z", "y", "x"), add = TRUE)
#
 image3D(z = 100, colvar = volcano, zlim = c(0, 150),
   clab = c("height", "m"))
  
#
 image3D( x = 0.5, colvar = volcano, xlim = c(0, 1), 
   ylim = c(0, 1), zlim = c(0, 1))

 image3D( y = 0.5, colvar = volcano, add = TRUE)

#
 image3D( z = 1, colvar = volcano, 
   x = seq(0, 1, length.out = nrow(volcano)),
   y = seq(0, 1, length.out = ncol(volcano)), 
   xlim = c(0, 2), ylim = c(0, 2), zlim = c(0, 2))
 image3D(y = 2, colvar = volcano, add = TRUE, 
    shade = 0.2,
    x = seq(0, 1, length.out = nrow(volcano)),
    z = seq(1, 2, length.out = ncol(volcano)))
 image3D(x = 2, colvar = NULL, col = "orange", add = TRUE, 
    y = seq(0, 1, length.out = nrow(volcano)),
    z = seq(1, 2, length.out = ncol(volcano)))

# reset plotting parameters
 par(mfrow = pm)